Skip to content

Commit

Permalink
A pass on simplification of the main spec... pull out most of the
Browse files Browse the repository at this point in the history 
vocabulary definition to the activitystream2-vocabulary document, begin
extracting out the best practices information to a separate document.
  • Loading branch information
@jasnell
jasnell committed Aug 21, 2014
1 parent 209873c commit 816f024
Show file tree
Hide file tree
Showing 3 changed files with 660 additions and 989 deletions.
251 changes: 251 additions & 0 deletions activitystreams2-bestpractices.html
View file
@@ -0,0 +1,251 @@
<section id="linguistic-forms" class="appendix informative">
<h2>Linguistic Forms</h2>

<p>
The Activity Streams format has been intentionally designed to be
flexible in how machine-readable statements about past, present or
future actions can be expressed. Implementations will often translate
Activity Statements into human-readable sentences such as
"John uploaded a file" or "John will upload a file". To make such
transformations possible, it is necessary for implementations to
have some sense of how the machine-readable JSON serialization
maps to common natural-language linguistic forms.
</p>

<section id="intransitive">
<h2>Intransitive Activity</h2>

<p>
In many situations, the <code><a>actor</a></code> of an Activity also
serves as the direct object. For example, if I say,
"The process terminated", then the "process" is both the actor and the
object. Such statements are formally known as being "intransitive".
</p>

<figure><figcaption>To describe intransitive activities,
simply omit the <code><a>object</a></code> property:</figcaption>
<pre class="example highlight json">{
"actor": {
"objectType": "process",
"displayName": "Build Process"
},
"verb": "terminate"
}</pre></figure>

</section>

<section id="transitive">
<h2>Transitive Activity</h2>

<p>
In a "transitive" activity, the actor and direct object are distinct
entities. This is the form most commonly expressed using the
Activity Streams format. For instance, if I say, "Joe posted a blog
entry", the actor is "Joe" and the "blog entry" is the direct object.
</p>

<figure><figcaption>Transitive activities contain distinct <code><a>actor</a></code> and
<code><a>object</a></code> properties:</figcaption>
<pre class="example highlight json">{
"actor": "acct:joe@example.org",
"verb": "post",
"object": {
"objectType": "article",
"title": "A Blog Entry",
"content": "..."
}
}</pre></figure>

</section>

<section id="ditransitive">

<h2>Ditransitive Activity</h2>

<p>
In "ditransitive" activities, there exist distinct actor, direct and
indirect objects. The indirect object specifies the target to which
the action on the direct object has been directed. For instance, in
"Joe posted a blog entry to his Weblog", the indirect object (or
"target") is "Joe's Weblog".
</p>

<figure><figcaption>Ditransitive activities contain <code><a>actor</a></code>,
<code><a>object</a></code>, and <code><a>target</a></code> properties.</figcaption>
<pre class="example highlight json">{
"actor": "acct:joe@example.org",
"verb": "post",
"object": {
"objectType": "article",
"title": "A Blog Entry",
"content": "..."
},
"target": {
"objectType": "blog",
"title": "Joe's Weblog"
}
}</pre></figure>
</section>

<section id="tense-and-aspect">

<h2>Expressing tense and aspect</h2>

<p>
By using the <code><a>startTime</a></code>, <code><a>endTime</a></code>,
<code><a>duration</a></code> and <code><a>status</a></code>
properties, Activity statements can be used to express past, present
or future actions. Implementations should never rely on an activity
statement's verb identifier to determine the tense or aspect of the
action.
</p>

<figure><figcaption>To indicate an activity that has already concluded, the
startTime and endTime properties would be used to indicate past
points in time</figcaption>
<pre class="example highlight json">{
"actor": "acct:joe@example.org",
"verb": "post",
"object": "http://example.org/blog/entry/1",
"startTime": "2012-12-12T12:12:12Z",
"endTime": "2012-12-12T12:12:12Z"
}</pre></figure>

<figure><figcaption>If specific start and end times for a concluded activity are not
available, the <code><a>status</a></code> property can be used to expressly indicate
that the action has completed:</figcaption>
<pre class="example highlight json">{
"actor": "acct:joe@example.org",
"verb": "post",
"object": "http://example.org/blog/entry/1",
"status": "completed"
}</pre></figure>

<figure><figcaption>To indicate an activity that began in the past but is still ongoing,
only the <code><a>startTime</a></code> property would be used:</figcaption>
<pre class="example highlight json">{
"actor": "acct:joe@example.org",
"verb": "watch",
"object": "http://movies.example.org/movie/1",
"startTime": "2014-03-18T04:32:43Z"
}</pre></figure>

<figure><figcaption>The status property value "<code>active</code>" can also be used to identify
ongoing activities:</figcaption>
<pre class="example highlight json">{
"actor": "acct:joe@example.org",
"verb": "watch",
"object": "http://movies.example.org/movie/1",
"status": "active"
}</pre></figure>

<figure><figcaption>To indicate an activity that is expected to begin in the future, the
<code><a>startTime</a></code> property would indicate a future point in time:</figcaption>
<pre class="example highlight json">{
"actor": "acct:joe@example.org",
"verb": "cook",
"object": "http://recipes.example.org/recipe/1",
"startTime": "2015-12-23T12:34:21Z"
}</pre></figure>

<figure><figcaption>Or, alternatively:</figcaption>
<pre class="example highlight json">{
"actor": "acct:joe@example.org",
"verb": "cook",
"object": "http://recipes.example.org/recipe/1",
"status": "pending"
}</pre></figure>

<p>
The status values "<code>pending</code>" and "<code>tentative</code>"
differ in that the former is used to mark actions that are expected to
happen while the latter is used to mark proposed actions that may
(or may not) happen.
</p>

<p>
As an alternative to explicitly stating the <code><a>startTime</a></code>
or <code><a>endTime</a></code> properties, the <code><a>duration</a></code> property
can be used to indicate a specific duration of time relative to either
the <code><a>startTime</a></code> or <code><a>endTime</a></code>.
For instance, specifying an <code><a>endTime</a></code> of
"<code>2015-12-23T12:23:23Z</code>" with a <code><a>duration</a></code> of "<code>PT1H</code>",
implies a starting time of exactly "<code>2015-12-23T11:23:23Z</code>" (1 hour before the specified
ending time).
</p>

<p>
Note that the value of the <code><a>duration</a></code> property can be expressed
either as a non-negative integer specifying a number of seconds, or
as an [[!RFC3339]] <code>duration</code> string such as "<code>PT1H</code>", "<code>P1DT1H</code>", etc. For
Activity Streams 2.0 implementations for which backwards
compatibility with the Activity Streams 1.0 syntax is not critical,
the RFC 3339 string format is strongly recommended.
</p>

</section>

<section id="activity-duration">

<h2>Activity Duration</h2>

<p>
Actions expressed via the Activity Streams format can either be
instantaneous (semelfactive) or durative (having distinct start and
end times). The specific duration of an activity can be optionally
expressed using the <code><a>startTime</a></code>, <code><a>endTime</a></code>
and <code><a>duration</a></code> properties.
</p>

<p>
By default, all activities are assumed to occur instantaneously, that
is, occuring at one point in time without any specific duration.
Such events are indicated by omitting the <code><a>startTime</a></code>,
<code><a>endTime</a></code> or <code><a>duration</a></code> properties:
</p>

<figure><figcaption></figcaption>
<pre class="example highlight json">{
"actor": "acct:sally@example.org",
"verb": "post",
"object": "http://example.org/notes/1"
}</pre></figure>

<p>
An activity that occurs within a specific period of time can be
expressed using combinations of either: <code><a>startTime</a></code>
and <code><a>endTime</a></code>, <code><a>startTime</a></code> and
<code><a>duration</a></code>, or <code><a>endTime</a></code> and
<code><a>duration</a></code>. For example:
</p>

<figure><figcaption></figcaption>
<pre class="example highlight json">{
"actor": "acct:sally@example.org",
"verb": "watch",
"object": "http://movies.example.org/movies/1",
"startTime": "2014-05-23T12:23:12Z",
"endTime": "2014-05-23T13:25:15Z"
}</pre></figure>

<figure><figcaption></figcaption>
<pre class="example highlight json">{
"actor": "acct:sally@example.org",
"verb": "watch",
"object": "http://movies.example.org/movies/1",
"startTime": "2014-05-23T12:23:12Z",
"duration": "PT1H2M3S"
}</pre></figure>

<figure><figcaption></figcaption>
<pre class="example highlight json">{
"actor": "acct:sally@example.org",
"verb": "watch",
"object": "http://movies.example.org/movies/1",
"duration": "PT1H2M3S",
"endTime": "2014-05-23T13:25:15Z"
}</pre></figure>

</section>

</section>

0 comments on commit 816f024

Please sign in to comment.